Integration Guide Universal Robots LS

Note: We strongly recommend that you read the Robot communication overview before this integration guide.

Note 2: We strongly recommend that you use the latest version of this integration guide. It is included in the latest version of the Robot module. To download the Robot module, visit the official Photoneo website.

Contents

• 1 Prerequisites

• 2 Robot controller setup

  • 2.1 Network configuration

  • 2.2 Enabling Real-Time Data Exchange (RTDE)

  • 2.3 Loading the Robot module files

  • 2.4 Tool TCP setup

• 3 Robot module

  • 3.1 Connection procedures

  • 3.2 Request list

  • 3.3 Pick-related functions

  • 3.4 Example programs

  • 3.5 Error handling

  • 3.6 Info data and variables

• 4 Runtime

  • 4.1 Set the approach and deapproach offsets

  • 4.2 Teach positions

  • 4.3 Prerequisites

  • 4.4 Running the pho_main_basic_loc program

• 5 Robot module update

• 6 Version and brand ID

• 7 Migration

1 Prerequisites

This guide describes the Robot module for robots running PolyScope 5. Before you start the setup, make sure that your robot controller meets these requirements:

• E-Series controller with software version 5.10 or higher

• UR-Series controller - the supported software versions are not defined yet

• CB-Series controller - no longer officially supported

• RTDE service enabled on the robot (see 2.2)

• Photoneo vision controller with Locator Studio (LS) 1.5

This version of the robot interface was developed and tested with Universal Robots E-Series v5.22 and v5.11.

Robots with PolyScope X use a separate Robot module. It is described in its own integration guide.

To check the software version of your robot, go to Menu -> About:

The UR software version is listed on the first line:

2 Robot controller setup

2.1 Network configuration

First, configure the IP address of the robot controller port that communicates with the Photoneo vision controller. Go to Menu -> Settings:

Open System -> Network. Select Static Address as the network method and enter the IP address and Subnet Mask of the robot controller. This manual uses 192.168.1.2 and 255.255.255.0. Click Apply to confirm the changes.

Note: The subnet mask 255.255.255.0 is the same as a 24-bit subnet mask. For more combinations, see this table.

Example of a matching network configuration on the vision controller side:

• Vision controller IPv4 address: 192.168.1.1 / 24

• Robot controller IPv4 address: 192.168.1.2 / 24 (as configured in the previous step)

You can also use the Test Connection button on the Network page of the Photoneo vision controller to ping the Universal Robots controller.

Depending on the result of the test connection (ping command), you get a Robot Available or Robot Unavailable popup message. If the robot is unavailable, check the cabling and the network configuration again.

2.2 Enabling Real-Time Data Exchange (RTDE)

The vision controller reads the robot state directly from the UR controller. It connects to the Real-Time Data Exchange (RTDE) port 30004 and reads the joint positions and the TCP pose at 10 Hz (for robot visualization). No Robot State Server program has to run on the robot, but the RTDE service must be enabled and running on the robot.

To check that this service is running, go to Settings -> Security -> Services and make sure that RTDE is enabled.

2.3 Loading the Robot module files

The Photoneo UR robot interface consists of a single script file and several URP template programs:

• photoneo_scripts

  • photoneo_locator.script

• photoneo_examples

  • pho_calibration_basic_loc.urp

  • pho_calibration_auto_loc.urp

  • pho_main_basic_loc.urp

  • pho_main_basic_hand_eye_loc.urp

  • pho_main_basic_multi_vs_loc.urp

  • pho_main_change_solution_loc.urp

  • pho_main_get_status_loc.urp

  • pho_main_multiview_dynamic_loc.urp

  • pho_main_multiview_static_loc.urp

  • pho_main_reuse_scan_loc.urp

  • pho_main_change_bbox_loc.urp

  • pho_calibration_basic_hand_eye.urp

Copy both folders (the URP programs and the script) to the robot controller. The URP programs include the script through a Script node (type File) at the start of the program. PolyScope keeps a copy of the script inside the URP program. So the copy stored in a URP file can be older than the script file in the module.

Reload the script in every program you use. After you copy the files, open the program and select the Script node that includes photoneo_locator.script. Open the file again from the copied photoneo_scripts folder and save the program. Check that PHO_ROBOT_ID_STR in the loaded script is "UR/L/1.5.0XXXXXXXXXXXXXX".

You can copy the files to the robot controller in 2 ways:

• USB flash drive

• File transfer protocols such as SCP, FTP or SFTP

USB flash drive approach

Copy the folders from the downloaded module archive to a USB flash drive. Plug the drive into the USB port of the teach pendant or the robot controller.

Click Open -> Program:

Select usbdisk -> Photoneo UR Module -> LS 1.5 -> photoneo_examples:

To copy pho_main_basic_loc.urp to the robot controller, select the file in the list and click Copy.

Go to the target folder on the robot controller and click Paste to copy pho_main_basic_loc.urp there.

Repeat these steps for all template URP programs that you plan to use in your project. Copy the photoneo_scripts folder in the same way.

File transfer protocol approach

You can also copy files to the UR controller remotely, directly from your PC. Use WinSCP, FileZilla or another SFTP client. Use the following configuration for the connection:

• Protocol: SFTP

• Host: Robot IP address

• Port: 22

• User: root

• Password: easybot

If you prefer a command line, use the following scp command to copy the files:

$ scp -r photoneo_scripts photoneo_examples root@XXX.XXX.XXX.XXX:/programs/

2.4 Tool TCP setup

TCP setup - Locator Studio reads the UR TCP pose during calibration and hand-eye scan requests. The robot reports the tool position according to the TCP configuration on the Installation TCP tab. Locator Studio prefers an “all zeros” tool configuration, because it compensates the TCP offset directly on the vision system side. A zero tool configuration is also recommended for calibration.

The example programs send the flange pose (get_actual_tool_flange_pose()) with the calibration and hand-eye scan requests. So these requests do not depend on the active TCP. If you must use a non-zero tool, use the set_tcp command (see the UR Scripting language manual) to switch between the zeroed and the non-zeroed tool.

3 Robot module

The Robot module is designed for easy integration into existing applications.

Note: We strongly recommend that you read the Photoneo robotic API and Action requests documentation before this section.

3.1 Connection procedures

Warning: This procedure is in the API section of photoneo_locator.script. Do not edit it!

This procedure connects to the Action Request Server on the vision controller at the start of the program. You can send requests only after the connection is established.

Connection procedure

Description / Usage

Connect to Action Request Server pho_wait_for_server ( server_ip, port = PHO_LOCATOR_PORT_DEFAULT, max_attempt = 1 )

Description Opens a new connection to the Action Request Server (vision controller). Input parameters: server_ip - string with the IP address of the Action Request Server (vision controller) port - port of the Action Request Server [optional parameter - we recommend that you omit it, so that the default value 11003 is used] max_attempt - number of connection attempts [optional parameter - the default value is 1] Usage Call the procedure only once, at the start of the program. You can send requests only after the connection is established. pho_wait_for_server("192.168.1.1") Populates PHO_ERR_CODE - error code [global variable] After the socket is open, the procedure sends the brand ID UR/L/1.5.0XXXXXXXXXXXXXX. If the connection cannot be opened, it sets PHO_COM_FAILURE (3), shows a popup and stops the program.

3.2 Request list

This section describes the API calls of the Robot module. These procedures are intended for high-level control of the Locator Studio application. The request ID is the number sent to the vision controller. For a full description of each request, see Action requests.

Note: These procedures are defined in the API section of photoneo_locator.script. Do not edit them!

Note: Scan request and Meshing scan request do not wait for their response. pho_wait_for_scan_completion() reads the response. If you do not call it, the next request reads the response at its start. All other requests wait for their own response before they return.

Note: Only pho_wait_for_scan_completion() has the optional parameter timeout. Its default value -1 means that the timeout for receiving packets is infinite. UR Script cannot detect a closed socket, so in this case the robot program can hang on a receive. All other procedures wait for the response without a timeout.

Calibration requests

Request	Input variables	Output variables
Calibration start request (ID 25) pho_calib_start ( solution_id, vision_sys_id )	solution_id - solution ID vision_sys_id - vision system ID	PHO_ERR_CODE - error code [global variable]
Calibration add point request (ID 5) pho_calib_add_point ( tcp_pose )	tcp_pose - flange pose of the robot, use get_actual_tool_flange_pose()	PHO_ERR_CODE - error code [global variable]
Calibration save request (ID 27) pho_calib_save ( )	—	PHO_ERR_CODE - error code [global variable] pho_calib_acc - resulting calibration accuracy [µm, global variable] pho_camera_pose - resulting camera pose [global variable]
Calibration stop request (ID 26) pho_calib_stop ( )	—	PHO_ERR_CODE - error code [global variable]

Locator requests

Request	Input variables	Output variables
Scan request (ID 19) pho_request_scan ( vision_sys_id, tcp_pose = PHO_NO_POSE )	vision_sys_id - vision system ID tcp_pose - flange pose [optional parameter - required for hand-eye vision systems; use get_actual_tool_flange_pose()]	Note: The response is received by the procedure Wait for scan completion.
Meshing scan request (ID 30) pho_request_trigger_scan ( vision_sys_id, tcp_pose = PHO_NO_POSE )	vision_sys_id - vision system ID tcp_pose - flange pose [optional parameter - for hand-eye systems use get_actual_tool_flange_pose()]	Note: The response is received by the procedure Wait for scan completion or by the next request.
Reuse last scan request (ID 31) pho_run_loca_on_last_scan ( vision_sys_id )	vision_sys_id - vision system ID	PHO_ERR_CODE - error code [global variable] Note: Waits for its own response. Do not call Wait for scan completion after it.
Change bounding box request (ID 33) pho_request_change_bbox ( vision_sys_id, bbox_id )	vision_sys_id - vision system ID bbox_id - bounding box ID	PHO_ERR_CODE - error code [global variable]
Get objects request (ID 20) pho_request_get_objects ( vision_sys_id, num_of_req_objects )	vision_sys_id - vision system ID num_of_req_objects - number of requested object poses (0 = all)	PHO_ERR_CODE - error code [global variable] pho_object_poses - array of the received object poses as pose variables (p[x,y,z,ax,ay,az]), indexed from 0, up to 100 objects [global variable] pho_number_of_objects - number of received object poses [global variable] pho_dimensions_x - object width [mm, non-CAD solutions, global variable] pho_dimensions_y - object length [mm, non-CAD solutions, global variable] pho_dimensions_rot - object rotation [rad, non-CAD solutions, global variable] pho_nn_label - detected object label [AI solutions, global variable] pho_max_height - object height [mm, Layer solutions, global variable] pho_angle - object angle [rad, Layer solutions, global variable]
Get all objects pho_request_get_all_objects ( vision_sys_id )	vision_sys_id - vision system ID	Same as Get objects request with num_of_req_objects = 0 (all objects).
Get single object pho_request_get_single_object ( vision_sys_id )	vision_sys_id - vision system ID	Same as Get objects request with num_of_req_objects = 1. If one object was received without error, its pose is also copied to pho_object_pose.
Get vision system status request (ID 22) pho_request_get_vs_status ( vision_sys_id )	vision_sys_id - vision system ID	PHO_ERR_CODE - error code [global variable] pho_num_localized - number of objects localized [global variable] pho_num_ready - number of objects ready for picking [global variable] pho_process_state - 1 = vision system still processing, 0 = finished [global variable]

Solution requests

Request	Input variables	Output variables
Change solution request (ID 9) pho_request_change_solution ( solution_id )	solution_id - solution ID	PHO_ERR_CODE - error code [global variable]
Start solution request (ID 10) pho_request_start_solution ( solution_id )	solution_id - solution ID	PHO_ERR_CODE - error code [global variable]
Stop solution request (ID 11) pho_request_stop_solution ( )	—	PHO_ERR_CODE - error code [global variable]
Get running solution request (ID 12) pho_request_running_solution ( )	—	PHO_ERR_CODE - error code [global variable] pho_running_solution - solution ID [global variable]

Response receiving procedures

Response receiving procedures	Input variables	Output variables
Wait for scan completion pho_wait_for_scan_completion ( timeout = -1 )	timeout - receive timeout [optional parameter, -1 = infinite]	PHO_ERR_CODE - error code [global variable] Note: Reads the response of the last Scan or Meshing scan request. If no request is waiting for a response, it shows a popup and stops the program.

Communication check

Request	Input variables	Output variables
Communication check request (ID 100) pho_request_comm_check ( )	—	PHO_ERR_CODE - error code [global variable]

Auxiliary procedures

Procedure	Description
pho_enable_debug()	Sets PHO_DEBUG to True. The module then writes details about each request and response to the log (textmsg).
pho_info_error(code)	Returns the error code as text, for example "CALIBRATION RUNNING".

3.3 Pick-related functions

Get offset pose is an additional function. It calculates an approach or deapproach offset pose based on the selected method and axis.

Function	Input parameters	Returns
Get offset pose pho_get_offset ( pho_object_pose, pho_offset_value, pho_method = PHO_METHOD_DEFAULT, pho_axis_name = PHO_AXIS_NAME_DEFAULT )	pho_object_pose - target object pose pho_offset_value - offset magnitude, in meters pho_method - offset calculation method [optional parameter, one of "Tool Offset", "Tool Plane", "Base Offset", "Base Plane"; default "Base Offset"] pho_axis_name - axis along which the offset is applied [optional parameter, one of "X", "Y", "Z"; default "Z"]	pose p[x,y,z,ax,ay,az]

Method options:

• "Base Offset" - adds the offset along the selected axis in the base coordinate system

• "Base Plane" - overrides the value along the axis in the base coordinate system (the offset value is the absolute coordinate, in meters)

• "Tool Offset" - moves the pose back along the selected axis of the object pose (tool coordinate system) by the offset value

• "Tool Plane" - computes the intersection between the offset plane (base system) and the selected axis of the object pose

Use positive offset values for both the Tool and the Base methods. The function also checks that the object pose, the offset pose and two safety poses 20 mm beyond them are within the safety limits of the robot. If they are not, it shows the popup One or more calculated poses are not reachable. An invalid method or axis name also shows a popup.

For more details on how to use this function to set up the approach and deapproach offsets, see 4.1 Set the approach and deapproach offsets.

3.4 Example programs

The Photoneo UR module contains several URP template programs. They show how to use the requests listed in 3.2 Request list for various use cases. Before you run any of them, reload the script as described in 2.3.

URP example	Description
pho_main_basic_loc pho_main_basic_hand_eye_loc	This simple example shows the basic workflow: how to connect to a vision controller, send a scan request, request object poses, receive the object poses and execute picks. The example also shows error handling, because each function returns an error value in PHO_ERR_CODE. The hand-eye variant sends the flange pose with the scan request (tcp_pose=get_actual_tool_flange_pose()).
pho_calibration_basic_loc pho_calibration_basic_hand_eye pho_calibration_auto_loc	Calibration examples. Basic calibration (pho_calibration_basic_loc, pho_calibration_basic_hand_eye): first start the calibration manually in Locator Studio. The program moves to Calib_Home, then to Calib_Pose_1 … Calib_Pose_9 and calls pho_calib_add_point(get_actual_tool_flange_pose()) in each pose. At the end, it returns to Calib_Home. Save the result manually on the vision controller. Automatic recalibration (pho_calibration_auto_loc): this requires a successful first calibration and automatic recalibration enabled in the vision system settings. The program stops the running solution, starts the calibration with pho_calib_start(SOLUTION_ID, VISION_SYS_ID), adds the 9 points, saves the result with pho_calib_save() and ends with pho_calib_stop(). Teach all 9 calibration poses before the first run. The calibration error should usually stay below 3 mm. A higher error usually indicates a systematic problem in the calibration setup. If the error is above the allowed threshold, the save request returns error 467. Important: The calibration object must stay where it was during the first calibration. The calibration ball stays mounted in the same place on the flange or gripper and moves with the robot. The marker pattern stays in the same place in the cell. Otherwise, the automatic recalibration fails.
pho_main_basic_multi_vs_loc	Same as pho_main_basic_loc, but switches between two vision systems. The VISION_SYS_ID variable defines which vision system is scanned and asked for object poses. The switching is done at the end of the Photoneo Pick and Place Loop folder.
pho_main_change_solution_loc	Same as pho_main_basic_loc, but with all requests related to solution switching. At the start, it checks the running solution with pho_request_running_solution() and, if needed, stops it and starts solution 1 with pho_request_start_solution(). In the loop, it switches between solutions 1 and 2 with pho_request_change_solution(). The SOLUTION_ID variable defines which solution is activated. The switching is done in the Change Solution folder at the end of the Photoneo Pick and Place Loop folder.
pho_main_get_status_loc	Same as pho_main_basic_loc, but with calls of the pho_request_get_vs_status request. You can call pho_request_get_vs_status() repeatedly at short intervals during localization. It returns: pho_num_localized - number of objects localized pho_num_ready - number of objects ready for picking pho_process_state - 1 = vision system still processing, 0 = finished These variables are often used for advanced decisions, especially to find the best time to start the pick procedure. The example requests pho_num_ready objects.
pho_main_multiview_static_loc	Static meshing example. It shows how to stitch multiple scans together before localization. This is useful for complex scenes or large objects. The robot stops at each scanning position to trigger and capture a scan. Requirements: Set MESH_DYNAMIC to False to disable dynamic meshing. Procedure: The robot stops at each scanning waypoint (Start, Middle, End) and calls pho_request_trigger_scan(VISION_SYS_ID, get_actual_tool_flange_pose()). After each scan, pho_wait_for_scan_completion() waits until the scan is finished. When the capturing sequence is complete, a regular pho_request_scan() starts localization. It does not perform an actual scan; it only starts the localization process. For best performance, keep the total number of scans below 10.
pho_main_multiview_dynamic_loc	Dynamic meshing example. It uses Photoneo Instant Meshing together with the Parallel Structured Light technique of MotionCam-3D. Dynamic meshing cannot be used with standard PhoXi 3D Scanners. Procedure: A program thread calls pho_request_trigger_scan(VISION_SYS_ID, get_actual_tool_flange_pose()) repeatedly while MESH_DYNAMIC is True, with a pause of CAPTURE_GAP seconds (0.5 s in the example) between the scans. Each call first reads the response of the previous call. The main program sets MESH_DYNAMIC to True at the Start waypoint, moves through Middle to End and sets it back to False. Only the final meshing scan is followed by pho_wait_for_scan_completion(). A regular pho_request_scan() ends the capturing sequence and starts localization. It does not emit light; it only triggers localization. Keep the scanning trajectory smooth, avoid abrupt rotations and keep the scanned area within the field of view. Otherwise, tracking can be lost. For best performance, keep the total number of scans at 60 or less.
pho_main_reuse_scan_loc	Same as pho_main_basic_multi_vs_loc, but adds pho_run_loca_on_last_scan(). This is useful when the scene has not changed since the last scan, but localization must run again with a different configuration (for example, different objects, bounding boxes or settings). Procedure: A regular scan captures the scene for VS1. Then pho_run_loca_on_last_scan() reuses the scan data from VS1 for VS2. Localization runs again with a different configuration, without a new scan.
pho_main_change_bbox_loc	Same as pho_main_basic_loc, but switches between two bounding boxes of vision system 1 with pho_request_change_bbox(VISION_SYS_ID, BBOX_ID). This is useful when localization must run on a different region of interest. Procedure: Prepare the vision system with at least 2 bounding boxes. The BBOX_ID variable defines which bounding box is activated next. The switching is done in the Change Bounding Box folder at the end of the loop.

pho_main_basic_loc - program structure (comments and the approach / deapproach parameter folders are shortened):

Photoneo Locator Initialization
  Script: photoneo_locator.script
  IP_ADDRESS:="192.168.1.1"
  pho_wait_for_server(IP_ADDRESS)
  Approach Offset Parameters
    APPR_OFFSET:=0.1
    APPR_AXIS:="Z"
    APPR_METHOD:="Tool Offset"
  Deapproach Offset Parameters
    DEAPPR_OFFSET:=0.2
    DEAPPR_AXIS:="Z"
    DEAPPR_METHOD:="Base Offset"
Photoneo Pick and Place Loop
  VISION_SYS_ID=1
  MoveJ
    Scanning
  pho_request_scan(VISION_SYS_ID)
  pho_wait_for_scan_completion()
  NUM_OF_REQ_TAR:=3
  pho_request_get_objects(VISION_SYS_ID,NUM_OF_REQ_TAR)
  If PHO_ERR_CODE != 0
    (insert your own error handling)
  Else
    increment:=0
    Loop increment < pho_number_of_objects
      MoveL
        Pick_start
      Approach
        pho_object_pose:=pho_object_poses[increment]
        approach:=pho_get_offset(pho_object_pose, APPR_OFFSET, APPR_METHOD, APPR_AXIS)
        movej(approach,r=0.0)
      Grasp
        movel(pho_object_pose,a =0.1, v =0.5 )
        Gripper Command
      Deapproach
        deapproach:=pho_get_offset(pho_object_pose, DEAPPR_OFFSET, DEAPPR_METHOD, DEAPPR_AXIS)
        movel(deapproach,a=1.2,v=0.5)
      Placing
        MoveJ
          Before_place
        MoveL
          Place
        Gripper Command
        MoveL
          Deappr_place
      increment:=increment+1

3.5 Error handling

Each request resets PHO_OCCURRED_ERR to False and PHO_ERR_CODE to 0 when its response arrives. If an error occurs while the requested operation runs, the module sets the global variable PHO_OCCURRED_ERR to True and stores the error code in the global variable PHO_ERR_CODE. We recommend that you add error handling for your application after each synchronous request and response receiving procedure.

The module reacts differently to each kind of error:

• Error code from the vision controller (for example, 502 No object found): the module only sets PHO_OCCURRED_ERR and PHO_ERR_CODE. Your program decides what to do.

• Communication errors (connection failed, wrong response, bad data): the module shows a popup and stops the program, because PHO_COM_ERR_STOP is True.

• Timeout (5): the module only sets the flag and the error code.

• pho_wait_for_scan_completion() without a pending scan: the module shows a popup and stops the program.

To keep the program running after a communication error, set PHO_SKIP_ERR = True in your program. The module then only sets the flag and the error code and clears the socket. Use this only together with your own error handling.

For the error codes with their descriptions and troubleshooting, see Error codes.

The module defines the following error code constants in photoneo_locator.script:

Error code	UR Script constant
No error (0)	PHO_NO_ERROR = 0
Service error (1)	PHO_SERVICE_ERR = 1
Unknown request (2)	PHO_UNKNOWN_REQ = 2
Communication error (3)	PHO_COM_FAILURE = 3
Bad data (4)	PHO_BAD_DATA = 4
Timeout (5)	PHO_TIMEOUT = 5
Invalid solution ID (450)	PHO_INVALID_SOLUTION_ID = 450
Another solution running (451)	PHO_ANOTHER_SOL_RUNNING = 451
Deployment not started (452)	PHO_SOLUTION_START_ERROR = 452
Deployment is not running (453)	PHO_SOLUTION_NOT_RUNNING = 453
Deployment did not stop (454)	PHO_SOLUTION_STOP_ERROR = 454
Solution is not complete (455)	PHO_SOLUTION_INCOMPLETE = 455
Invalid robot brand (457)	PHO_INVALID_BRAND_ID = 457
Solution already running (458)	PHO_SOL_ALREADY_RUNNING = 458
Solution access unauthorized (459)	PHO_SOLUTION_FORBID = 459
Invalid vision system (460)	PHO_INVALID_VS = 460
Calibration running (461)	PHO_CALIB_RUNNING = 461
Calibration not running (462)	PHO_CALIB_NOT_RUNNING = 462
Calibration stop error (463)	PHO_CALIB_STOP_ERROR = 463
Calibration start error (464)	PHO_CALIB_START_ERROR = 464
Calibration disabled (465)	PHO_CALIB_DISABLED = 465
Not enough points (466)	PHO_NOT_ENOUGH_POINTS = 466
Calibration accuracy above the allowed threshold (467)	PHO_ERROR_TOO_HIGH = 467
Scanner not available (468)	PHO_SCANNER_NOT_AVAIL = 468
Calibration not allowed (469)	PHO_CALIB_NOT_ALLOWED = 469

The Locator errors (500-511) have no constants in the module. Compare PHO_ERR_CODE with the number.

3.6 Info data and variables

Responses can contain additional values (see Info data). The module stores them in these global variables of photoneo_locator.script:

Key	Variable	Unit in robot
4	pho_dimensions_x[n]	mm
5	pho_dimensions_y[n]	mm
6	pho_dimensions_rot[n]	rad (converted from mrad by the module)
7	pho_nn_label	integer
8	pho_max_height	mm
9	pho_angle	rad (converted from mrad by the module)
10	pho_calib_acc	µm
11	pho_running_solution	integer
12	pho_num_localized	integer
13	pho_num_ready	integer
14	pho_process_state	0 / 1

[n] is the index of the object in pho_object_poses (starting from 0). pho_nn_label, pho_max_height and pho_angle contain the value of the last object received. Each Get objects request resets pho_max_height and pho_angle to -1. Keys 1-3 are used only in Bin Picking Studio.

Poses (pho_object_poses, pho_object_pose, pho_camera_pose) are UR poses p[x, y, z, rx, ry, rz] in meters and radians (rotation vector).

Other global variables used by the module:

Variable	Meaning
PHO_OCCURRED_ERR, PHO_ERR_CODE	Error flag and error code of the last request (see 3.5).
pho_object_poses, pho_number_of_objects	Object poses and their count from the last Get objects request.
pho_object_pose	Pose of the single object from pho_request_get_single_object().
pho_camera_pose	Camera pose from Calibration save request.
PHO_DEBUG	True writes details about each request to the log. Default False.
PHO_SKIP_ERR	True disables the popup and stop on communication errors. Default False.
PHO_COM_ERR_STOP	Constant, True: communication errors show a popup and stop the program.

4 Runtime

When the solution is fully configured on the vision controller, finish the remaining steps on the robot side and run the Locator Studio program.

4.1 Set the approach and deapproach offsets

In the Locator Studio example programs, you can set the approach and deapproach offset parameters. The pho_get_offset() function uses them. It is described in 3.3 Pick-related functions.

Input parameters for pho_get_offset():

• pho_object_pose - target object pose

• pho_offset_value - offset magnitude

• pho_method - offset calculation method

• pho_axis_name - axis along which the offset is applied

Approach offset configuration

The following variables in the Approach Offset Parameters folder define the approach (the default values of the examples are in brackets):

Variable	Description
APPR_OFFSET	Sets the offset distance in meters (0.1)
APPR_AXIS	Specifies the approach axis ("X", "Y", "Z") ("Z")
APPR_METHOD	Selects the approach method, as a string ("Tool Offset")

Available approach methods:

• "Base Offset" - adds the offset along the selected axis in the base coordinate system

• "Base Plane" - overrides the value along the axis in the base coordinate system

• "Tool Offset" - moves the pose back along the selected axis of the object pose (tool coordinate system)

• "Tool Plane" - computes the intersection between the offset plane (base system) and the selected axis of the object pose

Configure the deapproach settings separately in the Deapproach Offset Parameters folder: DEAPPR_OFFSET (0.2), DEAPPR_AXIS ("Z") and DEAPPR_METHOD ("Base Offset").

4.2 Teach positions

When you open pho_main_basic_loc.urp (or another template), touch up the following local poses before you run the program:

• Scanning

• Pick_start

• Before_place

• Place

• Deappr_place

4.3 Prerequisites

Do a final check before you run the Locator Studio interface from the robot side. Make sure that:

1. The Locator Studio solution is properly configured on the vision controller

2. The current script is loaded in the program (see 2.3)

3. The network setup on the robot side is complete and RTDE is enabled

4. All vision systems defined in the solution are calibrated

5. All local poses in the main program are touched up

6. Gripper commands are added to the Gripper Command folders and work

4.4 Running the pho_main_basic_loc program

Deploy your solution. If the communication is not established yet, the status of the Action Request Client (Robot) on the Deployment page is DISCONNECTED.

Note: We strongly recommend that you reduce the override speed to 20% before you run the program for the first time.

When the connection is established, the Action Request Client status changes to CONNECTED. The sensor should now capture the first scan, and localization should start to find objects.

If there is a pickable object in the scene and the robot controller has received its Cartesian pose, the robot should start to move towards the first object.

If the robot movement looks correct, continue moving the robot towards the first target and check that the path is correct. If the robot stops too far from the object or pushes the object too deep, adjust the object origin or the TCP setup of the tool.

When the robot movement looks correct, set up your own placing routine and slowly increase the speed back to 100%.

The robot should now pick and place objects with the Photoneo Universal Robots interface. When you tune your application further, use the example programs in 3.4 Example programs as a guide.

5 Robot module update

To update an existing Robot module to a version that is compatible with your Locator Studio version, follow these steps:

1. Load the new script - copy the new version of photoneo_locator.script to the robot controller. In your URP program, select the Script node that includes the old script, open the new file instead and save the program.

2. Review the API changes - read the API changes in the new version of the Robot module carefully. Update the API calls in your main program where needed.

To check the version of photoneo_locator.script, look at the script header (Locator communication library v 1.5.0) and the brand ID PHO_ROBOT_ID_STR.

6 Version and brand ID

Robot module version	1.5.0 (Locator Studio 1.5)
Brand ID (PHO_ROBOT_ID_STR in photoneo_locator.script)	UR/L/1.5.0XXXXXXXXXXXXXX (24 characters)
Action Request Server port	11003 (PHO_LOCATOR_PORT_DEFAULT)
Robot state	Read by the vision controller from RTDE port 30004

The module sends the brand ID right after the connection opens. Do not change it. The vision controller uses it to select the matching protocol version. For compatible Locator Studio versions, see the Robot module support matrix.

7 Migration

1.4 -> 1.5: The Info data protocol has changed. Every value is sent with its own key and is stored in the variables listed in 3.6. New variable: pho_nn_label. The brand ID is UR/L/1.5.0XXXXXXXXXXXXXX. Replace the script as described in 5 Robot module update. For details, see LS migration guide 1.4 -> 1.5.